Query IBAN Holder Name

Overview

This API verifies whether a provided account holder's name matches the corresponding IBAN. It is typically used to validate recipient information during fund transfers.

API URL

• UAT (Testing): https://uat.test2pay.com/sgs/api/transfer/getIbanHolderName
• Production: https://api.payby.com/sgs/api/transfer/getIbanHolderName

Request Parameters

HTTP Headers

Attributes

• Content-Language String
  • The language for the response message. Defaults to English.
  • Example value: en
  • Maximum length: 10
• Content-Type String Required
  • Media type of the request body.
  • Required for operations with a request body.
  • Format: application/json
• sign String Required
  • Request signature using private-key cryptography.
  • Ensures the payment gateway can verify the request origin.
  • Example value: RSA_SIGNATURE_BASE64_STRING
• Partner-Id String Required
  • Unique partner identifier.
  • Example value: 200001200101
  • Maximum length: 12

HTTP Body

• requestTime Timestamp Required

  Request time of the order. If the request time is more than 15 minutes away from the current time, the request will be rejected. This parameter is used to prevent repeated requests for orders that should have been cancelled due to timeouts.

  Example value: 1581493898000

• bizContent Object

  Attributes

  • merchantOrderNo String Required
    • Unique identifier for the merchant's order.
    • Example value: Me23484
    • Maximum length: 64
  • holderName String Required
    • Name of the beneficiary. Transmitted securely (encrypted).
    • Example value: Bruce Lee
    • Maximum length: 100
  • Iban String Required
    • International Bank Account Number. Transmitted securely (encrypted).
    • Maximum length: 34
  • swiftCode String
    • Improves accuracy if provided.
    • Example value: ARABAEADDER
    • Maximum length: 11
  • beneficiaryAddress String
    • Transmitted securely.
      If the bank account is personal, this field is required.
      The combined length of holderName and beneficiaryAddress must not exceed 140 characters, or the transfer may fail.
    • Example value: Liwa Street off Khaliffa Street
    • Maximum length: 100
  • amount Money Required
    • Payment amount for the transaction.
    • Example value: 12.34
  • memo String Required
    • Remarks or notes for the payment.
    • Example value: Bonus
    • Maximum length: 128
  • notifyUrl String
    • URL for receiving backend notifications.
    • Maximum length: 200
  • riskInfo String
    • Extension field in JSON format
    • Example value: {"scene":"casino","level":"hight"}
    • Maximum length: 255

GetIbanHolderNameRequest

• holderName String(256) Required

  • Encrypted account holder name.

• iban String(256) Required

  • Encrypted IBAN number.

Request Sample

Http Header
{
    "Content-Language": "en",
    "Content-Type": "application/json",
    "Partner-Id": "200000018128",
    "sign": "<signature_string>"
}

Http Body
{
    "body": {
        "bizContent": {
            "holderName": "<encrypted_holder_name>",
            "iban": "<encrypted_iban>"
        },
        "requestTime": 1585142880000
    }
}

Response Parameters

HTTP Headers

Attributes

• Content-Language String
  • The language for the response message. Defaults to English.
  • Example value: en
  • Maximum length: 10
• Content-Type String Required
  • Media type of the request body.
  • Required for operations with a request body.
  • Format: application/json
• sign String Required
  • Request signature using private-key cryptography.
  • Ensures the payment gateway can verify the request origin.
  • Example value: RSA_SIGNATURE_BASE64_STRING
• Partner-Id String Required
  • Unique partner identifier.
  • Example value: 200001200101
  • Maximum length: 12

HTTP Body

• head ResponseHeader Required

  • Response metadata.

• body GetIbanHolderNameResponse

  • Core response payload.

  • ibanHolderName IbanHolderName Required

    • Contains the name match result.

Response Sample

Http Header
{
    "sign": "<response_signature>"
}

Http Body
{
    "head": {
        "applyStatus": "SUCCESS",
        "code": "0",
        "msg": "SUCCESS",
        "traceCode": "1133"
    },
    "body": {
        "ibanHolderName": {
            "holderNameMask": "xxx*** xxx*** xxx***",
            "nameMatchingLevel": "1",
            "nameMatchingResult": "TRUE"
        }
    }
}

Return Codes

Code	Message	Cause	Workaround
0	SUCCESS	Success	-
400	INVALID_PARAMETER	Invalid parameter	Adjust request parameters.
400	REQUESTTIME_TOO_EARLY	Request time is too early	Adjust request time.
400	REQUESTTIME_TOO_LATER	Request time is too late	Adjust request time.
402	RATE_LIMIT_REJECT	Too many requests	Reduce request frequency.
403	UNAUTHORIZED	Unauthorized API call	Contact Botim Money.
404	SERVICE_NOT_AVAILABLE	API service unavailable	Contact Botim Money.
500	SYSTEM_ERROR	System error	Contact Botim Money and retry.
504	SERVICE_TIMEOUT	Service timeout	Retry later.
601	RISK_FAIL	Risk control validation failed	Adjust business logic.
62101	WRONG_IBAN_FORMAT	Incorrect IBAN format	Correct IBAN format.
62102	NAME_NOT_FOUND	Name not found for IBAN	Use a valid IBAN.
62103	QUERY_API_UNAVAILABLE	Query interface unavailable	Retry later.